ShowTable of Contents
You will need the following to complete this walkthrough.
- Domino server.
- Notes Designer + Admin client.
- Internet Explorer.
In the examples below the following refer to your Notes/Domino install location.
- Domino: C:\Domino
- Notes: C:\Notes
Change these to match your server as required.
Creating a self signed certificate in Domino
1. Open the administrator client and connect to your domino server.
2. From the file menu select “Application -> New Application”.
3. Fill in the “New Application” dialog as follows (Click on "Show Advanced Templates" to access all settings).
- Server: Your server name
- Title: Certificate Authority
- File name: cca50.nsf
- Template Server: Your server name
- Template: Domino Certificate Authority (6)
- File name: cca50.ntf
4. Click OK. The database should now be open.
5. Select the file menu and “Application -> Access control”
6. Make sure the following ACL settings are correct.
- Default: Author and “Create Documents” enabled.
- Your login: Manager and [CAPrivlegedUser] role.
7. Click OK.
8. Click on “1. Create Certificate Authority Key Ring & Certificate”
9. Fill out the form as follows.
- Key ring file name: CAKey.kyr
- Key Ring Password: [enter password]
- Password Verify: [enter password]
- Key Size: [default value]
- Common Name: [common name for cert]
- Organization: [org]
- Organization Unit: [org unit] (optional)
- City or Locality: [city/locality] (optional)
- State: [State]
- Country: [2 character country code]
10. Click “Create Certificate Authority Key Ring”
NOTE: If any strange errors occurred while following the steps above, cancel out, close the database and reopen and try again.
11. Copy the CAKey.kyr from your notes data folder to your domino data folder.
12. At this point to make it easier, close the database and open the “Server Certificate Admin” database (certserv.nsf) on the server.
NOTE: To avoid “Invalid or nonexistent document” errors, use the Notes client to open the database and not the admin client. See the tech note 1106171
for more details.
13. Click “View and edit keyrings”.
14. Click the button “Select key ring to display”. For “Enter keyfile to access” put in the full path to the key file in your domino data area. (eg. C:\Domino\data\CAKey.kyr)
15. Click OK.
16. Enter in your password for your CAKey file and click OK. The view should be updated with the CAKey details. Once this is OK, close the view to return to the main options.
17. Select “Create key ring with Self-Certified Certificate”
18. Fill out the form as follows.
- Key ring file name:C:\Domino\data\keyfile.kyr
- Key Ring Password: [enter password]
- Password Verify: [enter password]
- Common Name: [URL of your server]
- Organization: [org]
- Organization Unit: [org unit] (optional)
- City or Locality: [city/locality] (optional)
- State: [State]
- Country: [2 character country code]
19. Click “Create Key Ring with Self-Certified Certificate.
20. Make sure the following files exist.
C:\Domino\data\CAKey.kyr
C:\Domino\data\keyfile.kyr
C:\Domino\data\keyfile.sth
Set up SSL on the Domino server
1. Open the Administrator client and select the “Configuration Tab” and then the “Current Server document”.
2. Select the tab “Ports” then “Notes Network Ports”. Click “Edit Server”.
3. Leave the settings as the default (change “SSL key file name” to “keyfile.kyr” if needed.
4. The lower part of the page, keep the defaults except for “SSL Port status”, change that to “Enabled”.
5. Go to your Domino server console and start/restart the HTTP server with the following commands.
6. Test your SSL connection by connecting to the default page in a browser. (eg. https://testserver.local.lan)
7. You will get a warning that there is something wrong with the certificate. This is normal and you can continue to the website to make sure you get the website displaying.
NOTE: At this point if the connection fails you can use the following notes.ini settings to debug the issue (you will need to restart http to generate the debug).
DEBUG_SSL_ALL=3
SSL_TRACE_KEYFILEREAD=1
Convert the SSL certificate to CER format
1. Open the https address in Internet Explorer. You will get a warning. Click “Continue to website (not recommended)”.
2. Click the red marker beside the certificate error and then click “View certificates”.
3. Click on the Details tab and click “Copy to File...”
4. The Certificate export wizard will appear. Click Next.
5. Click on “Base-64 encoded X.509 (.CER)” and then click Next.
6. Save the file to the security folder in the Domino JVM. Call it server.cer (eg. C:\Domino\jvm\lib\security\server.cer)
7. Click Next, then click Finish. You should get a confirmation the export succes
Adding the certificate to a Java keystore and trusting the CA certificate
1. Open a command window.
2. To make sure you are using the Domino JVM type in the following commands.
set JAVA_HOME=C:\Domino\jvm
set PATH=%JAVA_HOME%\bin;%PATH%
3. Change to the jvm security folder.
cd C:\Domino\jvm\lib\security
4. Copy the cacerts file to cacerts.jks (do not work directly off cacerts)
5. Type in the following command. Change [alias] to a meaningful alias.
keytool -import -v -trustcacerts -alias [alias] -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit
NOTE: cacerts default password is "changeit". As the password suggests, you should change this if deploying.
6. You will be given details about the certificate and asked to trust it. Type Y and hit enter. You should get the message “Certificate was added to keystore”
7. Type in the following command. Again change the [alias] to a meaningful alias, for example your servers url.
keytool -import -alias [alias] -file server.cer -keystore mykeystore.jks
8. You will be asked to give the keystore a password and retype it.
9. You will be given details about the certificate and asked to trust it. Type Y and hit enter. You should get the message “Certificate was added to keystore”
Creating a sample Java application to connect to the server
1. Open the Designer client. While you can create an agent with the code, for ease of this tutorial we will be creating a Java project instead.
2. Select “Window -> Open Perspective -> Java” menu option.
3. Select “File -> New -> Java Project” menu option.
4. For Project name give it “Test SSL” and click finish.
5. Expand the project on the right hand side and right click on the src folder. Select “New -> Class” menu option.
6. For the name of the file type “TestSSL” and click finish.
7. In the source window paste in the following code.
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.Socket;
import javax.net.ssl.SSLSocketFactory;
public class TestSSL {
// Change these settings below to your setup as required.
static final String hostName = "localhost";
static final String urlFile = "/";
static final int sslPort = 443;
static final String keyStore = "C:/Domino/jvm/lib/security/mykeystore.jks";
static final String keyStorePassword = "changeit";
static final String trustStore = "C:/Domino/jvm/lib/security/cacerts.jks";
static final String trustStorePassword = "changeit";
static final boolean debugSSL = false;
public static void main(String args[]) throws Exception {
// Set up SSL parameters.
System.setProperty("javax.net.ssl.keyStore",keyStore);
System.setProperty("javax.net.ssl.keyStorePassword", keyStorePassword );
System.setProperty("javax.net.ssl.trustStore", trustStore);
System.setProperty("javax.net.ssl.trustStorePassword", trustStorePassword);
System.setProperty("java.protocol.handler.pkgs","com.sun.net.ssl.internal.www.protocol");
if (debugSSL) System.setProperty("javax.net.debug", "ssl");
SSLSocketFactory ssf = (SSLSocketFactory) SSLSocketFactory.getDefault();
Socket s = ssf.createSocket(hostName, sslPort);
BufferedWriter out = new BufferedWriter(new OutputStreamWriter(s.getOutputStream()));
BufferedReader in = new BufferedReader(new InputStreamReader(s.getInputStream()));
out.write("GET " + urlFile + "/ HTTP/1.1\n");
out.write("Host: " + hostName + "\n\n");
out.flush();
String string = null;
while ((string = in.readLine()) != null) {
System.out.println(string);
}
in.close();
out.close();
s.close();
}
}
8. Run the code. It should display the HTML from the selected web page.
9. If it fails to work change the constant debugSSL to true.
10. Run the program again, it will generate certificate debug information to help in finding the root cause.